/**
 * Copyright 2008 Adam Ruggles.
 * 
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 * 
 * http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package kiff.security;

import java.util.Collection;
import java.util.Enumeration;

/**
 * Access Control List interface.
 * @author Adam
 * @version $Id: Acl.java 38 2008-09-21 07:40:51Z a.ruggles $
 */
public interface Acl {
	/**
	 * Adds a new entry to the access control list.
	 * @param entry The access control entry to add.
	 */
	void addEntry(AclEntry entry);

	/**
	 * Returns an enumeration of the entries in the access control list.
	 * @return an enumeration of the entries in the access control list.
	 */
	Enumeration<AclEntry> getAclEntries();

	/**
	 * Returns the name of the Forum ACL.
	 * @return the name of the Forum ACL.
	 */
	String getName();

	/**
	 * Returns the owner of the access control list.
	 * @return The owner of the access control list.
	 */
	Principal getOwner();

	/**
	 * Returns the permission for the specified role.
	 * @param principal The principal whose permission is to be returned.
	 * @return The permission for the specified role.
	 */
	Permission getPermission(Principal principal);

	/**
	 * Returns whether or not any one of the principals in the collection has the specified permission.
	 * @param principals A collection of principals to check.
	 * @param permission The permission value to review.
	 * @return <code>true</code> if any of the principals in the collection has the specified permission,
	 * otherwise <code>false</code>.
	 */
	boolean hasPermission(Collection<Principal> principals, Permission permission);

	/**
	 * Returns whether or not the principal has the specified permission.
	 * @param principal The principal whose permission is being reviewed.
	 * @param permission The permission to review.
	 * @return <code>true</code> if the principal has the specified permission, otherwise <code>false</code>.
	 */
	boolean hasPermission(Principal principal, Permission permission);

	/**
	 * Returns whether or not any one of the principals in the array has the specified permission.
	 * @param principals An array of principals to check.
	 * @param permission The permission value to review.
	 * @return <code>true</code> if any of the principals in the array has the specified permission,
	 * otherwise <code>false</code>.
	 */
	boolean hasPermission(Principal[] principals, Permission permission);

	/**
	 * Removes an entry from the access control list.
	 * @param entry The access control entry to remove.
	 */
	void removeEntry(AclEntry entry);

	/**
	 * Sets the name of the Forum ACL.
	 * @param name the name to set.
	 */
	void setName(String name);

	/**
	 * Sets the owner of the access control list.
	 * @param owner The new owner of the access control list.
	 */
	void setOwner(Principal owner);
}
